
IBM C Set ++ News No.6 
November 93 

Hello Again 

It's been six months since our last issue of C Set + + News, and 
there's certainly a lot to tell you. In this issue: 

• our new products 

- C Set + + V2.1, page 2 

- C Set + + FirstStep, page 6 

- C Set + + for AIX/6000, page 16 

- Pricing and Packaging, page 7.. plus the latest on the US 
promotional prices 

- Documentation, page 14 

• give us your feedback on our documentation, page 22 

• feedback on ColoradOS/2, page 18 

• what's happening with registration cards, page 20 

• getting support - where to go for help, page 20 
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• our European friends join us, page 21 

• C Set + + and DB2/2, page 27 

• OS/2 ™ 2.1 APIs, page 32 

• What Drag/Drop is all about, page 29 

• last but not least, hints and tips, page 32.. including a special 
Q&A section on the Browser, page 41.. and how to save your 
hard disk space by using C Set direct from the CD-ROM, page 
38 

Now you know why it's been six months since the last issue! The C 
Set team has been working hard on the new offerings, so, sit back 
and read about what we've been up to. And as usual, tell us what 
you think - mail or fax the Reader's Reply Form at the end of the 
NL. We welcome your comments. 


The Family Grows 

The last six months has seen major activity on the C Set front. We 
started with the the announce of C Set + + 2.0 ™ in May. Then, in 
September 93, C Set + + for AIX ™ was announced by our colleagues 
in the AIX area (for details of that product, see the section called 
"Another member of the family"). Now - October 28th in the USA 1 
to be exact - the family has grown again, with three new products: 
one replacement, two brand new. Here's what we've done: 

• C Set + + V2.1, replacing V2.0 

• C Set + + FirstStep, an entry level version of C Set + + 

• C Set + + Class Fibraries Source V2.1, source code for the UI and 
Collection class libraries 


C Set + + V2.1 

First, a quick review of what components make up C Set + + . There 
are three major parts: 

1. C/C+ + Tools (the package name for the grouping of the com¬ 
piler, debugger, EXTRA code analyzer, browser and class 
libraries) 

2. WorkFrame/2 ™ (the development environment) 


1 This is the announce date for C Set + + in the USA. Other countries may have announced at a later date. 
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3. Developer's Toolkit (TK for short, it has resource and other tools 
in it) 

This new release builds on the 2.0 version of C Set + + , with enhance¬ 
ments in four major areas: 

1. KASE:Set ™ 2 makes its debut as a visual User Interface builder 

2. Toolkit 2.1 is now available in the product, allowing you to take 
full advantage of OS/2 2.1 

3. WorkFrame/2 has undergone a facelift, and returns as V2.1, uti¬ 
lizing the object-oriented Workplace Shell to provide a com¬ 
pletely new development environment 

4. The User Interface Class Library has been enhanced with the 
addition of Drag/Drop classes 


KASE:Set 

Building a CUA 91 UI just became simpler with the availability of 
KASE:Set. Instead of slowly building your UI from scratch using 
PM or the UI class library, you can be up and running in a fraction 
of the time with exactly the UI you want, backed by expert level 
source code, all courtesy of KASE:Set. All it takes is an idea of what 
you want and the ability to point and click. You choose your 
windows, dialogs, menus, notebooks, all the components of your UI, 
and KASE:Set turns that into expert code in C or C+ + your choice. 
And anyone who hates to comment code is in for a treat: KASE:Set 
does it for you! 

And there's more. Because KASE:Set defines the linkages between 
the UI components and application logic, providing hooks to user 
code, it's easy to integrate application logic with the source code you 
produce. That way you can spend your time on the application logic 
rather than the UI. 

Although experienced programmers can use KASE:Set to increase 
their productivity, building new applications or renovating old ones, 
novice developers will be particularly glad of KASE:Set. They can 
"read along with KASE:Set" through the expert level code, with the 
comments explaining what's being done and how. It's an excellent 
way to learn. 

How to get started? With KASE:Set, there are 5 steps: 


2 KASE:Set is a trademark of KaseWorks Inc 
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1. Prototype the individual elements of your UI using KASE:Set's 
modular interface designers 

2. Combine the reusable UI components and your application logic 
into a complete UI definition 

3. Generate the source code in C or C+ + 

4. Edit and integrate any additional logic into the resulting code 
using whichever editor you want 

5. Compile the source using C Set + + 

You're done. No run-times. No royalties. No proprietary languages. 
Just a business critical application with an expertly coded UI. 

KASE:Set is from KASEWORKS Inc, and is an introductory 
product based on a subset of features found in their KASE:VIP tool. 
Not sold separately by KASEWORKS or IBM, it is packaged along 
with C Set + + , and comes with its own documentation. 


Toolkit V2.1 

Version 2.0 of C Set + + contained Toolkit 2.0. To take advantage of 
OS/2 2.1 (e.g. the new APIs, the kernel debugger, MMPM/2) 
requires TK 2.1, and that's now part of C Set + + . Just in case you're 
not sure what the TK is, it's full of build, resource, PM, and 
MMPM/2 tools, as well as the SOM precompiler. And of course, 
there are sample programs. TK is mandatory for use with the 
C/C+ + Tools part of C Set + + . 


WorkFrame/2 V2.1 

WorkFrame organizes your files into logical units or projects. It's 
also a tool integrating environment that allows you to use your 
favourite tools be they DOS, Windows, or OS/2. 

WorkFrame/2 now takes advantage of the Workplace Shell. It has all 
the function of V 1.1 plus: 

• it adapts to the user's project environment, rather than the other 
way around 

• projects can consist of source and object files spanning multiple 
directories, and can have one target such as .EXE or .DLL 

• it associates each project with multiple actions, including com¬ 
piling, debugging, making, linking, browsing, profiling, and pre¬ 
processing 

• multiple developers can now work concurrently on a single 
project by plugging in their own source control system 
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Version 1.1 continues to be provided in the package, so you get both 
versions when you buy V2.1 of C Set + + . 

User Interface Class Library 

UICL has grown. There's been around a 15% growth in the func¬ 
tions, primarily due to Drag/Drop support (many of the classes have 
been enhanced to support Drag/Drop directly). Also included are: 

• New Classes: 

- IGraphicPushbutton - Allowing the full use of bitmaps and 
icons on push buttons. 

- IThread:: Cursor - allowing the threads in an application to 
be iterated. 

• New Functions 

- IWindow: 

— Zorder manipulation functions that allow the tab order 
of windows to be changed dynamically. 

— Constructor to allow the wrapping of a generic window 
handle. 

— Send/Post of events added. 

— Support to disable the update of a window. 

- INotebook 

— Sizing functions allowing a notebook page to be sized to 
the windo w stored in it. 

- IFrameWindow 

— Sizing functions allowing a frame window to be sized to 
the client window. 

— Functions for querying and setting the frame border size. 

- IContainerControl 

— New functions for querying the contents of data in a 
column and for rendering the data in all supported 
formats. 

— New function to query the splitbar. 

- IMultiCellCanvas 

— Development functions to allow movable grid lines in the 
canvas to help adjust the initial position of the canvas 
contents. 

- StaticText 

— Functions to allow the use of halftone, underscore, and 
strikeout. 

• Updated Hard and Soft Copy Documentation and sample pro¬ 
grams. 
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Plus ... 

CSDs 1 and 2 are integrated into V2.1 of C Set + + . And there are 
new packaging and pricing options. See "Packaging and Pricing" to 
find out what C Set + + looks like these days. 

C Set + + FirstStep 

If you're a new or non-professional programmer, a student, getting 
started in C or C+ + , or just don't want to spend a lot of money, C 
Set + + FirstStep is for you. It's a slimmed down version of C Set + + 
at a correspondingly lower price. You get: 

• the same compiler/debugger tools as C Set + + V2.1 except for 
optimization 

• three class libraries 

- Standard Classes (Task, Iostream, Complex) 

- Collection Classes 

- Application Support Classes (Date, String, Time) 

• Toolkit V2.1 

• WorkFrame/2 VI.1. Notice that's 1.1, not the later 2.1 version. 

EXTRA (the code analyzer) and the Browser aren't in FirstStep, nor 
is the User Interface Class Library. KASE:Set isn't there either. 

None of these things are essential to begin C or C+ + , but they're tre¬ 
mendously useful once you get going, or if you program for a living. 

If you think you need those, then you need C Set + + V2.1. 

One other thing to note about FirstStep. Program Service is NOT 
provided for this product, although users can find hints and tips on 
the CompuServe ™ 3 service. 

Now to a most important consideration: money. What is the corre¬ 
spondingly lower price we mentioned? Check out the Packaging and 
Pricing section, and see how little it costs to join the C Set family. 

C Set + + Class Libraries Source 

Source code for the UI and Collection class libraries is now available. 
This hasn't been introduced as part of the main C Set + + product; 
instead it's a separate product with its own packaging and price tag. 


3 tm Trademark or registered trademark of CompuServe Inc 
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What about me? - I'm not in the USA 

All the stuff you just read on content of the products is valid wher¬ 
ever you live. The pricing and packaging options may not be. The 
products are developed in IBM's Software Solutions laboratories in 
Boeblingen, Cary, Lexington, and Toronto, and are released to the 
USA, Canada, and three geographical groups of countries: Latin 
America, Asia Pacific, and Europe/Middle East/Africa. Within these 
groups, each country is decides exactly when and how to announce 
the products, based on specific needs, wants and customs. This 
means that they may need to change the product to take into 
account local rules and regulations, e.g. have different ordering 
instructions, maybe new part numbers, include local licensing terms, 
and establish local prices. As a result, many countries often 
announce later than the USA does, and also have a later GA 
(General Availability) date than the USA. This has been the case 
with the announcements you're reading about now. At time of going 
to press, most countries in the world were planning to announce this 
version in either November or December 1993. To find out the 
details on your specific country announcement please contact your 
local IBM representative. 

And I'm in Asia Pacific 

Both C Set + + and FirstStep were released to the countries in this 
geography (except Japan) at the end of October. 

At press time, Australia, Singapore, Malaysia, Hong Kong/China 
and most of the single byte countries have announced our new pro¬ 
ducts. The AP announcement letters are AP73-1471 C Set + + ) and 
AP1473 (FirstStep), if you want more details, or check with your 
usual channel. 


Pricing and Packaging 

Packaging 

A new packaging option is available for both V2.1 and FirstStep: 
CD-ROM Pak. This is a CD-ROM with Group 1 documentation 
(how to and basic manuals) included in hardcopy. You can still buy 
the CD-ROM on its own - it has all the documentation softcopy - so 
now there are three choices: 

1. diskette version with group 1 manuals hardcopy, group 2 soft- 
copy 

2. CD-ROM version, all documentation in softcopy 

3. CD-ROM Pak, group 1 manuals in hardcopy, group 2 softcopy 
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Because of the new licensing options, the volume packs, and the 
upgrades from previous products, there are many part numbers for 
you to think about when you're ordering any of the new products. 
We're not listing every part number here, just the most common 
ones. For example, we don't discuss what it costs to buy any of the 
three components (C/C+ + Tools, WorkFrame, or Toolkit) separately. 
If you don't see what you want, or you need any further help, please 
contact IBM through your local source (IBM office, IBM rep, 
dealer/distributor, CompuServe, IBMLink TalkLink BBs, or 
workframe@vnet.ibm.com or cset2@vnet.ibm.com, etc.). 

USA Ordering and Prices 

A Promotion has been announced 

Since the announcement of C Set + + V2.1 was made on October 
28th, a promotion has been arranged to offer reduced prices to eli¬ 
gible customers. 

You are eligible if you fall into one of these two categories: 

1. if you acquired C Set + + V2.0 by upgrading from either 
WorkSet/2 or C Set/2 Vl.O, or 

2. if you acquired C Set + + V2.0 after September 9, 1993. 

Let's say that another way: 

• If you bought the old C Set/2 or WorkSet/2 product, then 
bought C Set + + , you are eligible for the promotion. It doesn't 
matter when you bought any of the products, just that you went 
from Vl.O to V2.0, and now want V2.1. 

• If the first product you bought was C Set + + V2.0, then you are 
eligible if you acquired it after September 9th, 1993. 

Before you rush off and order V2.1, be aware of these things: 

• Promotional prices are available only from the IBM 
1-800-3IBM-OS2 number or your dealer. The promotion may 
vary from dealer to dealer. 

• If your V2.0 of C Set + + was not acquired directly from IBM, 
proof of purchase (copy invoice) will be required if you are pur¬ 
chasing from the 1-800 number. 

• Orders must be placed on or before January 31, 1994. 

• The promotion cannot be combined with any other discount or 
allowance. 
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Did you note the third point? The promotion is a limited time. It 
expires on January 31, 1994. Then the prices go back to the previous 
"street" and announced prices. 


Parts and Prices 

Now to the part you've been waiting for: the prices and the part 
number you order, if you qualify. There are just three part numbers, 
one for CD-ROM, one for 3.5" diskette, and one for the CD-ROM 
Pak. They are: 


Description 

Part Number 

Price 

C Set + + V2.1 3.5" Upgrade 

82G3788 

$99 

C Set + + V2.1 CD Upgrade 

82G3789 

$59 

C Set + + V2.1 CD-ROM Pak Upgrade 

82G3790 

$79 


Note: Once the promotion ends (January 31, 1994), the prices will 
revert to those below. Those customers not eligible for the promotion 
will pay the charges listed next. 

Non-Promotion Pricing 

These are the prices that you pay 

1. if you are not eligible for the promo 

2. after January 31, 1994 if you are eligible for the promo 


These prices come in two flavours: IBM announced price and some¬ 
times a "street" price. The latter is a lower-than-announced price 
that you pay at the IBM 1-800-3IBM-OS2 number. 

Things to note: 

• not every part or product has a "street" price. 

• the quoted "street prices" are available ONLY at the 
1-800-3IBM-OS2 phone number, after the price promotion 
expires. 

• your dealer/distributor may also sell for less. 

• not every pricing option is available everywhere, e.g. the volume 
packs are not sold through the 1-800-3IBM-OS2 number. Any 
restrictions are noted in the appropriate text. 

• 5.25" diskette version is no longer available. 
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When you buy C Set + + V2.1 or FirstStep, you now have several 
options open to you: 

• single unit pricing (price for buying one copy) 

• additional licensing packs (you may know this as LAN licensing) 

• volume packs (packs of 5, 10, 25, 50 and 100 at a lower price) 

• upgrade prices from C Set/2, WorkSet/2, and C Set + + V2.0 

How (and what) to order 

Decide which of the sections below refers to you, and read what 
pricing options/restrictions apply. Also, check if there's any pro¬ 
motion that IBM is offering that might give you a lower price. 


1 (a) you don't have a C Set product today 
(b) you want to buy a single copy 


Description 


Media 

USA part Ann'd price 1- 

800-3IBM-OS2 

C Set + + 

2.1 

3.5" 

82G3732 $695 

$459 

C Set + + 

2.1 

CDROM 

82G3735 $595 

$395 

C Set + + 

2.1 

CDROM 

Pak 82G3736 $645 

$425 

C Set + + 

FirstStep 

3.5" 

82G3744 $149 

$99 

C Set + + 

FirstStep 

CDROM 

82G3746 $129 

$85 

C Set + + 

FirstStep 

CDROM 

Pak 82G3747 $149 

$99 


2 (a) you have a C Set product already, on 3.5" or 5.25" diskettes 

(b) you want C Set + + V2.1 on 3.5" diskettes 

(c) you want to buy a single copy 


What you have today What to order Ann'd price 


1-800-3IBM-OS2 


WorkSet/2 82G3900 $265 

C Set/2 82G3901 $265 

C Set + + V2.0 82G3902 $265 


$175 

$175 

$175 


3 (a) you have a C Set product already, on 3.5" or 5.25" diskettes 

(b) you want C Set + + V2.1 on CD-ROM, no hardcopy doc 

(c) you want to buy a single copy 


What you have today What to order Ann'd price 


1-800-3IBM-OS2 


WorkSet/2 82G3904 $165 

C Set/2 82G3905 $165 

C Set + + V2.0 82G3906 $165 


$109 

$109 

$109 


4 (a) you have a C Set product already, on 3.5" or 5.25" diskettes 

(b) you want C Set + + V2.1 on CD-ROM Pak 

(c) you want to buy a single copy 


What you have today What to order Ann'd price 


1-800-3IBM-OS2 


WorkSet/2 82G3908 $215 

C Set/2 82G3909 $215 

C Set + + V2.0 82G3910 $215 


$139 

$139 

$139 
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5 (a) you have a C Set product already, on CDROM 

(b) you want C Set + + V2.1 on 3.5" diskettes 

(c) you want to buy a single copy 

What you have today What to order Ann'd price 1-800-3IBM-OS2 


C Set + + V2.0 82G3903 $265 $175 

6 (a) you have a C Set product already, on CDROM 

(b) you want C Set + + V2.1 on CDROM again 

(c) you want to buy a single copy 

What you have today What to order Ann'd price 1-800-3IBM-OS2 


C Set + + V2.0 82G3907 $165 $109 

7 (a) you have a C Set product already, on CDROM 

(b) you want C Set + + V2.1 on CDROM Pak 

(c) you want to buy a single copy 

What you have today What to order Ann'd price 1-800-3IBM-OS2 


C Set + + V2.0 82G3911 $215 $139 


**** BU YING in volume **** 

** First, consider if any promotion is currently available. If so, ** 

** t hen it may be cheaper for you to use the promotion. For example, ** 

** if you own 25 copies, you could buy one of the volume packs we ** 
** sh ow below. However, if you qualify for the promotion we mention ** 
** earlier, then it makes more sense to upgrade using the promotion ** 

** discount. Be aware, though, that the promotion does not allow any ** 

** vol ume purchase - you must do a one for one upgrade. That means ** 
* * if you have 5 copies and you qualify, you can't order 25 at the ** 

** promotional prices. You can only buy 5, one for each of the _ ** 

* * copies you own. _^ 


8 (a) you want to buy C Set + + V2.1 in volume 
(b) you want 3.5" diskettes 

What you have today How many you want What to order Price 


Doesn't matter 

5 

82G3924 

$2,260 

Doesn't matter 

10 

82G3925 

$4,170 

Doesn't matter 

25 

82G3926 

$9,555 

Doesn't matter 

50 

82G3927 

$17,370 

Doesn't matter 

100 

82G3928 

$31,270 


NOTE: 1. Volume Packs are ONLY available from the 1-800-IBM-CALL number, 
or from your IBM representative. 

2. Not available from dealers or distributors. 

3. There are no "street" prices for Volume Packs 
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9 (a) you want to buy C Set + + V2.1 in volume 
(b) you want CD ROM, no hardcopy doc 


What you have today How many you want What to order Price 


Doesn't matter 

5 

82G4451 

$1,930 

Doesn't matter 

10 

82G4452 

$3,570 

Doesn't matter 

25 

82G4453 

$8,180 

Doesn't matter 

50 

82G4454 

$14,870 

Doesn't matter 

100 

82G4455 

$26,770 

NOTE: 1. Volume Packs are ONLY available from the 1-800-IBM-CALL number. 

or from your IBM 

representative. 



2. Not available from 

dealers or distributors. 


3. There are no "street" prices for Volume Packs 


10 (a) you want to buy C 

Set + + V2.1 in 

volume 


(b) you want CD ROM 

Pak (CD ROM 

with hardcopy doc) 


What you have today How many you want What to order Price 

Doesn't matter 

5 

82G4456 

$2,095 

Doesn't matter 

10 

82G4457 

$3,870 

Doesn't matter 

25 

82G4458 

$8,870 

Doesn't matter 

50 

82G4459 

$16,120 

Doesn't matter 

100 

82G4460 

$29,0020 


NOTE: 1. Volume Packs are ONLY available from the 1-800-IBM-CALL number, 
or from your IBM representative. 

2. Not available from dealers or distributors. 

3. There are no "street" prices for Volume Packs 

11 (a) you have now got C Set + + V2.1 

(b) you want one extra license but don't want the actual physical 
package shipped to you - you will copy the product yourself, or 
allow ONE more user LAN access 

(c) you DON'T want IBM to send you proof of this extra license 

What you have today What to order Ann'd price 1-800-3IBM-OS2 


C Set + + V2.1 82G3916 $585 $386 

12 (a) you have now got C Set + + V2.1 

(b) you want one extra license but don't want the actual physical 
package shipped to you - you will copy the product yourself, or 
allow ONE more user LAN access 

(c) you DO want IBM to send you proof of this extra license 

What you have today What to order Ann'd price 1-800-3IBM-OS2 


C Set + + V2.1 82G3920 $585 $386 
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13 (a) you have now got C Set + + V2.1 

(b) you want X extra licenses but don't want the actual physical 

packages shipped to you - you will copy the product yourself, or 
allow X more users LAN access 


How many extra 


What you have today 

licenses you want 

What to order 

Price 

C Set + + 

V2.1 

5 

82G3929 

$1,900 

C Set + + 

V2.1 

10 

82G3930 

$3,510 

C Set + + 

V2.1 

25 

82G4443 

$8,040 

C Set + + 

V2.1 

50 

89G4444 

$14,620 

C Set + + 

V2.1 

100 

82G4445 

$26,320 


NOTE: 1. Additional Licensing Volume Packs are ONLY available from the 
1-800-IBM-CALL number, or from your IBM Representative 

2. Not available from dealers or distributors. 

2. There are no "street" prices for Addition License Volume Packs 


14 (a) you want the source code for the class libraries 

What you have today What to order Ann'd price 


Doesn't matter 61G1400 $695 

NOTE: 1. The Source Code product is ONLY available from the 1-800-IBM-CALL 
number, or from your IBM representative. 

2. It is not available from dealers or distributors. 

3. There is no "street" price for the Source Code product 

15 (a) you want hardcopy documentation for C Set + + V2.1 

What you have today Which doc What to order Ann'd price 1-800-3IBM-OS2 


Doesn't matter Group 1 82G3741 $55 $36 

Doesn't matter Group 2 82G3742 $90 $60 

NOTE 1. 1-800-3IBM-OS2 sells documentation in groups and singly 

2. 1-800-IBM-CALL sells documentation in groups only 

3. Dealers/distributors sell documentation in groups and singly 

4. IBM reps sell documentation in groups only 


16 (a) you want hardcopy documentation for C Set + + FirstStep 

What you have today Which doc What to order Ann'd price 1-800-3IBM-OS2 


Doesn't matter Group 1 82G3755 $20 $20 

Doesn't matter Group 2 82G3756 $74 $50 

NOTE 1. 1-800-3IBM-OS2 sells documentation in groups and singly 

2. 1-800-IBM-CALL sells documentation in groups only 

3. Dealers/distributors sell documentation in groups and singly 

4. IBM reps sell documentation in groups only 


Whew! I hope you're still with us - that's quite a lot of information, 
but it reflects our commitment to meeting our customer's buying 
needs. And we're not finished yet. How do you get documentation? 
What's in the documentation groups? How do you order the groups? 
What softcopy comes with which packaging option? Lots of doc¬ 
umentation questions; lots of answers! 
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Documentation 

Manuals for both C Set + + and FirstStep come singly and in two 
groups. The groups are: 


Product 

Which manuals 

Part Number 

C Set + + 

Group 1 

82G3741 

C Set + + 

Group 2 

82G3742 

CSef++ FirstStep 

Group 1 

82G3755 

C Set + + FirstStep 

Group 2 

82G3756 


Which manuals are in which groups? 


Product 

Manual 

Grp 

Part 

Number 

C Set+ + V2.1 

C/C+ + Tools Prog'g Guide 

1 

S61G1181 

C Set+ + V2.1 

C/C+ + Tools Debugger Intro 

1 

S61G1184 

C Set+ + V2.1 

C/C+ + Tools Browser Intro 

1 

S61G1397 

C Set+ + V2.1 

C/C+ + Tools EXTRA Intro 

1 

S61G1398 

C Set+ + V2.1 

C/C+ + Tools Reference Summary 

1 

S61G1441 

C Set+ + V2.1 

C/C+ + Tools UICL User's Guide 

1 

S82G3743 

C Set+ + V2.1 

C/C+ + Tools Installation Card 

1 

none 

C Set+ + V2.1 

WorkFrame/2 VI.11ntro 

1 

S61G1428 

C Set+ + V2.1 

WorkFrame/2 V2.1 Intro 

1 

S82G3740 

C Set+ + V2.1 

Developer's Toolkit Getting Started 

1 

none 

C Set+ + V2.1 

MM PM/2 Getting Started 

1 

none 

C Set+ + V2.1 

C/C+ + Tools C+ + Language Refei 
ence 

-2 

S61G1185 

C Set+ + V2.1 

C/C+ + Tools C Language Refer¬ 
ence 

2 

S61G1399 

C Set+ + V2.1 

C/C+ + Tools C Library Reference 

2 

S61G1183 

C Set+ + V2.1 

C/C+ + Tools Collection Class Lib 
Reference 

2 

S61G1178 

C Set+ + V2.1 

C/C+ + Tools UICL Reference 

2 

S82G3738 
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Product 

Manual 

Grp 

Part 

Number 

C Set + + V2.1 

C/C+ + Tools Standard Class Lib 
Reference 

2 

S61G1180 

FirstStep 

FirstStep Tools Programming 

Guide 

1 

S82G3748 

FirstStep 

FirstStep Tools Debugger Intro 

1 

S82G3749 

FirstStep 

FirstStep Tools Reference 

Summary 

1 

S82G3750 

FirstStep 

FirstStep Tools Read Me First 

1 

none 

FirstStep 

WorkFrame/2 VI.11ntro 

1 

S61G1428 

FirstStep 

Developer's Toolkit Getting Started 

1 

none 

FirstStep 

MM PM/2 Getting Started 

1 

none 

FirstStep 

FirstStep Tools C+ + Language Ref 

2 

S82G3760 

FirstStep 

FirstStep Tools C Language Refer¬ 
ence 

2 

S82G3761 

FirstStep 

FirstStep Tools C Library Refer¬ 
ence 

2 

S82G3759 

FirstStep 

FirstStep Tools Collection Class 
Library Reference 

2 

S82G3757 

FirstStep 

FirstStep Tools Standard Class 
Library Reference 

2 

S82G3758 

FirstStep 

FirstStep Tools Application Class 
Library Reference 

2 

S82G3905 

Class Library 
Source 

Class Library Source: Getting 

Started 

n/a 

none 


What format comes with what? 


Read across the table to see in what formats the documentation is 
shipped with the products. Remember,we ship you IBM BookMan- 
ager Read so you can read the .BOO files. 

Also, note that the IPF and BookManager (.BOO) files may be 
accessed either from your hard drive or directly from the CD-ROM. 
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Product 

Medium 

Group 1 

Group 2 

C Set + + V2.1 

Diskette 

Hardcopy 

IPF files 

C Set + + V2.1 

CD-ROM 

Postscript and 
.BOO files 

IPF files and 
.BOO files 

C Set + + V2.1 

CD-ROM Pak 

Hardcopy and 
Postscript and 
.BOO files 

IPF files and 
.BOO files 

C Set + + First Step 

Diskette 

Hardcopy 

IPF files 

C Set + + FirstStep 

CD-ROM 

Postscript 

IPF files 

C Set + + FirstStep 

CD-ROM Pak 

Hardcopy and 
Postscript 

IPF files 


Another Member of the Family 

C Set + + for AIX/6000 Version 2 is the follow-on version of XL C+ + 
Compiler/6000 VI. It consists of a native, optimizing compiler which 
compiles both C and C+ + programs, a browser, a HeapView 
debugger, a test coverage analyser and a set of class libraries. All 
tools that are shipped with C Set + + for AIX/6000 support both C 
and C+ + program development. 

C and C+ + Browser 

The browser is a post-compilation static analysis tool which allows 
users to examine their programs in many ways by formulating 
queries of the program database. This browser has been enhanced to 
support C as well as C+ + . 

Heapview Debugger 

The HeapView debugger is a new tool in the package. It enables 
users to detect memory corruption problems due to the dynamic 
nature of allocating and deallocating memory. 


Test Coverage Tool 

The test coverage tool provides information about how often dif¬ 
ferent statements in the code are used when the program is exe¬ 
cuting. Using this tool allows for quick identification of areas in the 
program that are not executed or tested. This tool has been 
enhanced to support C. 

Class Libraries 

Class libraries include: 

• USL 4 Class Libraries: iostreams, task and complex 


4 USL is a registered trademark of UNIX Syxtems Laboratories Inc. 
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• Collection class library 

• Application Support class library 

Class library example 

• Interviews 3.1 

In addition, C Set + + for AIX/6000 supports the following AIX tools: 

• debugger (dbx) 

• linker (id) 

• ixtools (i.e. prof, gprof, nm, vgrind, lex, yacc, cflow, cxref and 
lint) 

C Set + + for AIX/6000 V2 shares family ties with C Set + + for OS/2 
by sharing the same C+ + front end, using the same USL class 
libraries, and a Browser derived from the same source. Planned to 
be available in December 93 (with the CD-ROM coming a little 
later, this cousin to C Set + + for OS/2 has 5765-186 as its program 
number. 

For further details, consult your regular IBM channels or an Author¬ 
ised Business Partner. 


The Printed Word 

You may have heard the rumour about an ICLUI (or UICL as it's 
also known) book coming out, written by the folks who wrote the 
product. 

It's no rumour. Although the book isn't likely to be published until 
Winter 94, we can tell you that the title of the book currently is 
"OS/2 V2.1 C+ + Class Library Power GUI Programming" 

The book will cover all aspects of programming using the User Inter¬ 
face class library. Included are class descriptions, design rationale, 
and how to add extensions as well as sample programs, answers to 
frequently asked questions, and problem determination and tuning 
techniques. 

The authors are, in alphabetical order, Bill Law, Kevin Leong, Bob 
Love, and Hiroshi Tsuji. Publisher is Van Nostrand Reinhold. 
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International Phoenix Alliance 

One topic that turns up in our mailbag quite regularly is the Interna¬ 
tional Phoenix Alliance. Customers want to know what it is we're 
running and can they join. The truth is that it isn't IBM. The Alli¬ 
ance consists of OS/2 customers who have a continuing interest in 
OS/2 and its products. They see the role of their organization as 'the 
voice of the small user', but welcome all users with concerns, ideas 
and an interest in the future of OS/2. 

Membership is open to anyone anywhere, from the individual home 
user to the small business owner, from the IS professional at major 
corporations, to the college student. Dues are US$32. For further 
details contact Jack Hiatt in the USA at 404-445-6453, or 
74160,2656 on CompuServe. 


Thank You 

With another version of C Set out the door, it is timely to remember 
a particular group of people who helped make the product what it is. 
I'm not talking about the IBM developement team who put it 
together, but about you, our customers. Thousands of you, both 
internally and externally, put C Set products through their paces, 
giving us valuable feedback. You found bugs, made suggestions, and 
kept us - and continue to keep us - on our toes. From all of us in 
OS/2 C/C+ + Development, our sincerest thanks. 


Rocky Mountain High 

Where were you the first week in November? If you weren't at 
ColoradOS/2 in Colorado Springs, USA, you missed a treat. You 
also missed meeting the editor of this newsletter. ColoradOS/2 is a 
week long conference for OS/2 lovers - programmers, writers, tech¬ 
nical coordinators, anyone, as long as they are technically oriented. 
The time is packed with sessions on anything and everything on 
OS/2, from becoming an OS/2 consultant to the mysteries of device 
drivers. And there are always sessions on various aspects of C Set. 

This year's conference was kicked off by Wayne Kovsky, the origi¬ 
nator and organizer of the whole thing, followed by a keynote 
address by John Soyring. Each morning there was a keynote 
speaker, then the rest of the day was given over to technical sessions. 
Each time slot there are 8-10 topics to choose from, but as they are 
all repeated a couple of times over the week, with careful planning 
you can attend everything you want without missing anything. A 
splendid lunch was provided each day, and refreshments at the 
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breaks. Wayne even had Jolt served in large amounts - all bases 
covered! 

C Set + + was well represented at the conference, with Ian Ameline 
reprising his "Optimizations: Tips & Techniques" and "Writing High 
Performance Applications" sessions, and the User Interface Class 
Library folks there in full force. Kevin Leong, Hiroshi Tsuji, and 
Bill Law initiated their attendees into the arcane world of the UICL 
with 3 sessions: 

• Window and Handler Frameworks 

• Using the Advanced Layout Controls of the C Set + + Tools 

• Direct Manipulation 

In addition, your editor was around as an attendee, chatting to cus¬ 
tomers about the latest announce, answering marketing queries, and 
taking the opportunity to sound people out on requirements and 
future direction for C Set + + . 

Lest you think all the work is done in the presentation/class sessions, 

I should point out that one of the most valuable aspects of this tech¬ 
nical conference is - to use familiar computing terms - the networking 
and the peer to peer connection that goes on, in the breaks, at lunch, 
and into the evenings. Each day at 5:15, the audience reconvened in 
the main ballroom for a Q&A session that went on as long as was 
needed, which was often several hours. The amount of useful infor¬ 
mation, technical help, and just-in-case facts passed around was stag¬ 
gering. And it was augmented by European information too - this 
year, a full quarter of the attendees were from outside the USA, and 
I don't just mean Canada (although we were well represented). There 
were Belgians, Dutch, Germans, and the French there, to name a 
few. 

How did it all end? Bjarn Strousstrup, of C+ + fame, gave the closing 
keynote speech, reviewing the history of C+ + , and his feelings on its 
use. He fielded lots of questions and then joined us for lunch where 
he was available for questions and consultation. 

If you're sorry you missed it, there'll be another one next year, sched¬ 
uled for November. We'll carry details when it gets closer. Any 
questions, Wayne Kovsky's at 719-481-3389 (voice), 719-481-8069 
(fax). 
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We Know Who You Are 

But if we don't, we'd like to. It's vital that you return the registra¬ 
tion card you find in your product, so we can keep you up to date on 
the C Set family. In North America, your cards come to Toronto 
where we record your data. There's something in it for you: along 
with your support letter, we mail you a poster showing the User 
Interface Class Library classes. The support letter gives you a Cus¬ 
tomer Registration Number. This number isn't a replacement for 
any other customer number you may have been assigned by other 
IBM depts. It uniquely identifies you to the C Set team, and saves 
you having to quote your customer details over and over. 

If you're still waiting for your letter and poster, don't despair. We 
have received thousands of the cards, but we're well on the way 
through them all. 


Help! 

Many customers have asked about support channels - how you "offi¬ 
cially" contact us for help. There are lots of ways, depending on 
where you are and what you feel like doing - phoning, or messaging. 

Telephone 

In the USA and Canada, you can call 1-800-237-5511 to speak to a 
support person. This number connects you with the IBM Software 
Support Service, who handle our first level support. Have your cus¬ 
tomer number ready and identify yourself as a C Set user. You'll be 
given a number we can both use to track your problem. 


IBMLink - TalkLink 

In Canada and the USA, you can append C Set questions into the 
C-SET2 forum in the BBS section of TalkLink. Whilst some IBMers 
do log on directly onto IBMLink, mostly the questions are answered 
by C Set developers directly from our own internal electronic 
network which has a rapid turnaround tie-in with TalkLink's BBS's. 
We see the TalkLink BBS as a Customer Forum (CFORUM). 

You'll be talking with a whole bunch of developers on all the compo¬ 
nents of C Set, as well as experienced customers. These customers are 
not just from North America. As you can read in another article in 
this issue, European customers are also active on C-SET2. 

Code and other files such as CSDs and this newsletter are placed on 
TalkFink, usually in the OS/2 Selected Fixes area. Such actions are 
publicized in the forum, as are product announcements and other 
useful information. 
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CompuServe 


On this worldwide system, you'll find us in OS2DF1. We have two 
fora: C SET2 and C+ + . You'll find OS/2 advisors there too, all 
helping explain things to users of all skill levels. The two fora are of 
a Q&A nature. We also place files on CompuServe - CSDs, code, 
this newsletter, and other things when needed. They're in Library 
Section 4 and Library Section 5. 


Internet 

Yes, we do help you on the Internet. 5 You should direct your queries 
to cset2@vnet.ibm.com and workframe.vnet.ibm.com. They'll either 
be answered directly by the IBMers who monitor the Internet or, if 
that's not possible, forwarded to the person who can help. You may 
received email back, or a phone call; it depends on what you ask. 

Whichever method you use to ask us for help, please use your Cus¬ 
tomer Reference Number wherever possible. That way we know 
exactly who - and where - you are. If you don't have a CRN yet, 
you'll get one when you return your registration card. 


Hands Across the Sea 

As you'll have read in the previous article, some non-IBMLink cus¬ 
tomers are able to talk directly to the C Set team through the 
C-SET2 CLORUM. These customers are those on the EMEA DAP 
network, and we owe this joining of North Americans and Euro¬ 
peans to some code called GHostnet. Customers' appends on the 
DAP network are shadowed to the IBM TalkLink BBS's and then, 
along with "regular" TalkLink appends, shadowed into the appro¬ 
priate CFORUM on the IBM internal network, our VM host 
machines (hence Ghostnet). In other words, the Ghostnet code links 
the three together so we can all talk to each other - US customers to 
EMEA customers, and both of them to us, both directions. It's fast 
and easy. We find out even more about what our customers are 
doing with our product, customers help each other, and we all make 
new friends. To quote a European customer: it's a dream come true. 

For information on TalkLink, call 1-800-547-1283. For details of 
how to join the EMEA DAP, send a fax to 44 (for the UK) 256 
336778. 


5 There's also an Internet mailbox for the World Wide DAP (Developer Assistance Program). If you have questions 
about the program, or want to join, you can write to wwdap@vnet.ibm.com. 
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Inquiring Minds Want to Know 

There's one area of any software product that always generates dis¬ 
cussion: documentation. No matter how well something is written, 
whatever the quality of the paper, whoever the author is, we all have 
opinions on what was written and how it was said. We want a little 
more (or less!), we want it laid out differently, we feel things might 
be better expressed another way. In the past we've asked you what 
you think of C Set + + the product, the support, the marketing. Now 
we're asking again for your help. How do you feel about our doc¬ 
umentation? Please take a few minutes to complete our survey and 
mail/fax/email us your feedback. We want to improve our manuals - 
if you think we need to - if you think they're just fine the way they 
are, we're happy to know that too! 

C Set + + Documentation Survey 

Please help by answering the questions in this survey and returning it 
to us at: 


Method 

Mail 

Fax 

External Email 
Internal Email 
IBMLink 


How to reach us 

Pull the survey from the middle of the newsletter, 
fold and mail 

Canada 416-448-6057, attention Kathryn Fryer 
fryerk@ torolab4.vnet.ibm.com 
FRYERK at T0R0LAB4 
WZ00086 (Maxine Houghton) 


Please respond by January 15th, and feel free to add extra pages! 

Note: Don't forget to identify yourself - please include your name 
and address when you send in the survey. If you know your CRN, 
that's all you need to write on the survey to identify you. If you 
don't know what a CRN is ... Customer Reference Number; you 
receive one when you return your registration card. It saves a lot of 
writing. 
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1. What information units are you using and in which formats? (You can mark 
more than one if that's what you using. A V or an X is fine). 



Hardcopy 

Online 

(.INF/HLP) 

BookManager 

(.BOO) 

Postscript 

Technical Library Books 





Toolkit references 





PM reference 





WorkFrame/2 





C/C+ + Programming Guides 





Debugger! EXTRA 





Browser 





Class Libraries reference 





Other 






2. Which of the above do you use the most? The least? Why? 


3. How do you access or find information in the following: 
Format What you use 

Hardcopy Which? 

_ Index 

_ Contents 

_ Flip through pages 

_ Other (please specify) 

Online Which? 

_ Ctrl-H through EPM 

_ View from command line 

_ Contextual help (press pfl or pf2) 

_ KwikINF 
_ Index 
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_ Contents 

_ Search 

_ Other (please specify) 

BookManager Which? 

_ Index 

_ Contents 

_ Other (please specify) 

4. Printing from online information 

Do you print from the online information(IPF or BookManager)? 

Yes or No _ 

How often? _ 

How important to you is the ability to do so? 

What is an acceptable print quality? 

5. Why and when do you use the particular information unit in the different 
formats? (e.g. read the hardcopy on the way to work, to get an overview, 
use the online for quick reference when stuff...) 

Format What you use 

Hardcopy Used for - 

Online Used for - 

BookManager Used for- 

6. Can you always find the information you're looking for? 

_ always 

_ often 

_ sometimes 

_ rarely 

_ never 

How easy/or difficult was it to find? 

_ very easy 

_ not too difficult but not easy either 

_ very difficult 

How easy/difficult was it to understand when you found it? 
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_ very easy 

_ not too difficult but not easy either 

_ very difficult 

7. What do you like about the documentation we provide? Why? 


8. What do you like dislike about the documentation we provide? Why? 


9. What would you change if you could? (format? content? organization? pre¬ 
sentation? something else?) 


10. What format do you prefer for your documentation? (you can choose more 
than one) 

_ Hardcopy 

_ Online 

_ Context-help 

_ BookManager 

_ Postscript 

_ Other 

11. Have you a preference for which type of documentation appears in which 
format? 


12. Do you like the way we have distributed the C Set + + documentation? 
(e.g. the amount of hardcopy, of online; which books came hardcopy, which 
didn't; which came in which format?) What would you change? 


Thank you very much indeed for taking the time to fill in this survey. We appre¬ 
ciate your effort - your comments are valuable to us, as we evaluate our current 
documentation. 
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IBM C Set + + News No.6 November 93 issue 
Documentation Survey 


Fold here and tape . .fold here and tape . .fold here and tape . .fold here and tape . .fold here and tape . fold 


Software Services Toronto Lab 

IBM Canada Ltd 

TID - attn: Kathryn Fryer 

21/950/844/TOR 

844 Don Mills Road 

North York 

Ontario, M3C 1V7 

Canada 


Fold here and tape . .fold here and tape . .fold here and tape . .fold here and tape . .fold here and tape . .fold 
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Using WorkFrame/2 V2.1 to Enhance DB2/2 Productivity 

DB2/2 can be used with the new WorkFrame/2 Version 2.1 applica¬ 
tion development environment to gain higher levels of productivity. 

The first step in integrating DB2/2 is to create an action profile. An 
action profile is a set of actions associated with one or more projects. 
Figure 1 shows the settings note book for a DB2/2 Action Profile. 
Note that the PRE-COMPILE action has been created that identifies 
the SQLPREP tool. 



Figure 1. DB2/2 Action Profile 


The PRE-COMPILE action performs a precompile of the application 
using SQLPREP and automatically binds the application to the 
Sample database. PRE-COMPILE will also appear in the icon's 
pop-up menu. When you want to perform a precompile in the 
Workplace Shell, just point to the UPDATE.SQC icon and select 
PRE-COMPILE from its menu (Figure 2). 
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Figure 2. UPDATE.SQC Pop-up Menu 


You can choose to display the output from the precompile in a text 
window, a full-screen window, or a WorkFrame/2 monitor window 
(Figure 3). 
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Figure 3. WorkFrame/2 Monitor Window 


The output from the PRE-COMPILE action is the file UPDATE.C. 
UPDATE.C can now be compiled using C Set + + or C Set/2 and 
linked to create UPDATE.EXE. 
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For additional information, consult the following DB2/2 and 
WorkFrame/2 manuals: 

• DB2/2 Information and Planning Guide (IBM Doc No. S62G- 
3662) 

• DB2/2 Guide (IBM Doc No. S62G-3663) 

• DB2/2 Programming Guide (IBM Doc No. S62G-3665) 

• DB2/2 Programming Reference (IBM Doc No. S62G-3666) 

• DB2/2 SQL Reference (IBM Doc No. S62G-3667) 

• WorkFrame/2 Version 2.1 Introduction (IBM Doc No. S82G- 
3740) 

And don't forget, like us, the DB2/2 team have their own newsletter. 
If you're interested in receiving it, drop Lou Pedron a note or fax at 
416-448-2774 (V), 416-448-2114. 


Direct Manipulation Support 

Robust direct manipulation classes were added to the User Interface 
C Libraries in C Set + + V2.1, to support drag and drop between the 

following: 

• C Set + + applications 

• C Set + + applications and Workplace Shell file, shredder and 
printer objects 

The base direct manipulation classes implement a broad range of fea¬ 
tures that is found in the PM drag and drop support. 


Classes 

There are three major groups of classes within the User Interface 
Class Libraries. They are Handlers, Items, and Renders. 

Handlers 

Handler classes are defined to process direct manipulation events. 
Static functions are included to automatically create and attach han¬ 
dlers to a window. Default source and target handlers are provided 
and either or both may be attached to a window. The default source 
and target handlers handle all events and typically you do not need 
to derive from these classes. 

Items 

Item classes are defined to implement the specifics of the data object 
that is being manipulated. A generic item class is defined within the 
library that can be subclassed to define the behaviour of your data 
object. As a matter of fact, we derive 3 item classes from the generic 
class in order to support the Container, MLE, and Entry Field con- 
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trols. In most situations, the item class may be the only class you 
will need to subclass to provide direct manipulation support for your 
application. 


Renderers 

Renderer classes are defined to facilitate the transfer of data. Source 
and target renderer classes are defined which recognize several 
default rendering mechanisms and formats (RMFs) the we include: 

• A class library rendering mechanism that supports the following 
formats: 

- Text format for small (less than 256 bytes) text strings 

- Process format to detect if operation is in the same process 

- Shared memory format which allocates shared memory 
blocks to han die the rendering of the data 

The standard OS/2 rendering mechanisms for file, shredder, and 
print are also supported. 

Sample 

As previously mentioned, derived classes are provided to support the 
Container, MLE, and Entry Field controls. We have provided a 
sample program below that illustrates the container support. The 2 
lines of code in the main() function is all the code that is required to 
enable drag and drop for the sample program. You can copy or 
move objects either within or between containers in this sample. 
However, please note that these two containers are within the same 
process, which greatly simplifies the task. A sample has been 
included in the C Set + + V2.1 product which demonstrates copies 
between containers in separate processes. 
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#include < iframe.hpp> 

#include < ititle.hpp> 

#include < icnr.hpp> 

#include < idmhndlr.hpp> 

#include "sample.h" 

class MyWindow : public IFrameWindow { 

/* This is the demo window class for the sample program. ^ */ . 


public: 

7*- Constructor/Destructor- 

Objects of this class are constructed by providing the following: 
o A window ID 

- */ 

MyWindow ( unsigned long windowld ); 

.MyWindow ( ) {}; 

IContainerControl 
*cnr() { return(cnrCtl); } 


private: 

IContainerControl *cnrCtl; 
IContainerObject *space, 
♦starfleet; 


/* - . 

I main 

- */ 

void main() 

{ 

MyWindow myWinl (1000); 

MyWindow myWin2 (1001); 


/* Enable direct manipulation for both containers ... */. 

IDMHandler::enableDragDropFor( myWinl.cnr() ); 
IDMHandler::enableDragDropFor( myWin2.cnr() ); 


I Application: :current().run(); 

} 


/* - . 

I MyWindow Constructor. I . 

- */ 

MyWindow :: MyWindow ( unsigned long windowld ) : 
IFrameWindow ( windowld ), 

cnrCtl ( new ICnrCtl (windowld + 20, this, this, IRectangleQ) ), 
space ( 0 ), 
starfleet ( 0 ) 

{ 

/* Set the container as the frame client. ^ */ . 

this-> setClient(cnrCtl); 

/* Create the container objects ... */ . 

this-> space = new IContainerObject ("Astronaut", SPACE); 
this-> starfleet = new IContainerObject ("Captain", STARFFEET); 

/* and add them to the container. ^ */ . 

this-> cnrCtl-> addObject(space); 
this-> cnrCtl-> addObject(starfleet); 
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/* Set the container's attributes. ^ */ . 

this-> cnrCtl-> setDeleteObjectsOnClose(); 
this-> cnrCtl-> hideTitle(); 
this-> cnrCtl-> showIconView(); 
this-> cnrCtl-> arrangelconViewQ; 
this-> cnrCtl-> setExtendedSelection(); 

/* Add the title */ . 

ITitle title (this, "C Set + + DragDrop"); 

/* Size the frame window ^ */ . 

this-> sizeTo( ISize(250, 225) ); 

/* and show it ... ' ' ''' */ . 

this-> show(); 

} 

tttfttftttffttftttfftttftttfttftttffttftttfftttftttfttfttft SAMPLE.CPP ft* 

tttfttftttffttftttffttfftttfttftttffttftttffttfftttfttftttffttftttffttftttf 

#define SPACE 101 

#define STARFLEET 102 

ttff ttff ttff ttff tttf tttf tttf tttf tttf tttf tttf tttf tttf tttf tttf t SAMPLE.H tt‘ 

#include < os2.h> ^ ^ . 

#include "sample.h" 

ICON SPACE LOADONCALL space.ico 
ICON STARFLEET LOADONCALL starflee.ico 

ttff ttff ttff ttff ttff ttff ttff ttff ttff ttff ttff ttff ttff ttff ttff SAMPLE.RC ft* 


You Ask, We Answer 

We've crammed this newsletter full of all sorts of articles for you, 
and usually in this section, we add loads of Q&As. To avoid this 
issue becoming the size of a phone directory, we're reducing the hints 
and tips section. We'll be back to normal next issue. 


OS/2 2.1 APIs 

With all the new goodies, OS/2 2.1 is heady stuff. Be aware, though, 
that if you code your application to APIs that are new in OS/2 2.1, 
the application will not run under OS/2 2.0. To keep you on the 
straight and narrow, here are the API's that are new for OS/2 2.1. 
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WORKPLACE 


• wpAddPowerPage 

• wpAddPowerViewPage 

• wpChangePowerState 

• wpEjectDisk 

• wpLockDrive 

• WPPower (class) 

• wpQueryAssociatedProgram 

• wpQueryAutoRefresh 

• wpQueryDefStatusView 

• wpQueryDriveLockStatus 

• wpQueryPowerConfirmation 

• wpQueryPowerManagement 

• wpQueryRefreshRate 

• wpSetAssociatedFilelcon 

• wpSetAutoRefresh 

• wpSetDefStatusView 

• wpSetPowerConfirmation 

• wpSetPowerManagement 

• wpSetRefreshRate 


MESSAGES 

• WM_MOU SEMAP 

The 2.1 tools will execute on GA. Restrictions: 

• Use of the kernel debugger can only be used on the same level of 
OS/2 2.1. 

• Applications built with the toolkit will not run on 2.0 if they use 
the new 2.1 APIs. These include: 

- DosProtectClose 

- DosProtectEnumAttribute 

- DosProtectOpen 

- DosProtectQueryFHState 

- DosProtectQueryFilelnfo 

- DosProtectRead 

- DosProtectSetFHState 

- DosProtectSetFilelnfo 

- DosProtectSetFileLocks 

- DosProtectSetFilePtr 

- DosProtectSetFileSize 

- DosProtectWrite 

- WinChecklnput 

- WinFockPointerUpdate 

- WinQuerySysPointerData 
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- WinQueryVisibleRegion 

- WinSetPointerOwner 

- WinSetSysPointerData 

- WinSetVisibleRegionNotify 

- WinUnlockSystem 


Two for One 

A user recently asked: can I use both C Set/2, and C Set + + on the 
same system? This can be useful when I'm migrating applications 
from the original release to the next. 

You too may be pleased to know that the answer is yes, you can. 

The down side is that it'll take a little bit of work, especially if you 
want to use the two compilers simultaneously. The parts of the 
product that are common between the two releases (the C compiler 
and the PMD debugger) use the same names for executables, DLLs, 
header files, and environment variables in both releases. 

This fact means that using both compilers on the same system is not 
as simple as adding the necessary information for both compilers to 
your CONFIG.SYS, and compiling away. For example, the PATH 
environment variable is used to find the directory containing the 
compiler executables. The compiler whose directory is listed first in 
the PATH will always be executed first. The other poor compiler 
will be left out in the cold! 

But don't despair, there's an easy solution. Instead of using the set¬ 
tings of the C Set environment variables in the CONFIG.SYS file, 
where the settings will apply to every session, use command files to 
set the environment variables for the current session to the compiler 
of your choice. In fact, if you choose not to update your CON¬ 
FIG.SYS when installing C Set/2, or C Set + + , the installation 
program will create a command file called CSETENV.CMD which 
will do just what you want. If you didn't have C Set installation 
create the file, don't worry, here's all you need. 

Assume the compiler is installed in the ibmc directory of the x drive: 

SET PATH= x:\ibmc\bin;% PATH% 

SET DPATH= x:\ibmc\locale;x:\ibmc&bhelp;% DPATH 
SET BOOKSHELF= x:\ibmc\help;% BOOKSHELF % 

SET HELP= x:\ibmc\help;% HELP % 

SET LIB= x:\ibmc\lib;% LIB % 

SET INCLUDE= x:\ibmc\include;% INCLUDE% ; 

Note that these are the settings COMMON to the two compilers; 
there are additional settings for some of these variables, and further 
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variables that are specific to C Set + + . Since they are specific to one 
of the compilers, they can be safely set in CONFIG.SYS. 

Of course, you can create a program object to create a session with 
the appropriate environment set up. In fact, you'll find one that uses 
CSETENV.CMD in the C Set + + folder. To create an object for 
yourself, drag the Program template from the Templates folder to the 
folder (or desktop) in which you want to create your program object. 
When you drop the template on the folder, the Settings notebook for 
the object will be launched. Place a * in the "Path and file name" 
field, and the path and name of your command file in the "Parame¬ 
ters" field. For example, to use CSETENV.CMD from D:\ibmcpp: 

/K d:\ibmcpp\csetenv.cmd 

The /K option is required. You can then select the "General" tab to 
change the name of the session. 

Still with us? The use of command files to set environment variables 
for each session will solve most of our problem, but there is one diffi¬ 
culty left. The LIBPATH variable which tells your system where to 
search for DLLs can only be set in the CONFIG.SYS, and will 
apply to all sessions. Since the library, and PMD debugger DLLs 
for C Set/2, and C Set + + , have the same names, it would seem to be 
impossible to use both products simultaneously. To make matters 
even more difficult, the C Set + + compiler executables are dynam¬ 
ically linked to the library DLLs. However, to be able to use one 
compiler at a time, add a command to your command file to create 
C Set/2, or C Set + + sessions to copy the DLLs from the DLL direc¬ 
tory of the appropriate release to a new directory. If you place this 
directory in the LIBPATH before the DLL directories of either of 
the two compilers, then when you're working in a session, you'll get 
the correct DLLs. 

Finally, there is a way to use the DLLs from both compilers simul¬ 
taneously, but it will require further work on your part. It involves 
the use of the DLLRNAME utility included with C Set + + , to 
rename the DLLs from one release of the product. Because the C 
Set + + compiler uses the DLLs, it is easier to rename the C Set/2 
DLLs. Here's what you need to do: 

1. Edit the def files for the import libraries: 

• DDE4SBS.DEF - single-thread standard import library 

• DDE4SBM.DEF - single-thread migration import library 

• DDE4MBS.DEF - mulithread standard import library 

• DDE4MBM.DEF - multithread migration import library 

• DDE4NBS.DEF - subsystem import library 
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2. in each DEF file replace the name of the import library in the 
LIBRARY statement with your own unique name, which must 
be the same length as the original name. For example, in 
DDE4SBS.DEF, change: 

LIBRARY DDE4SBS INITINSTANCE TERMINSTANCE 
with: 

LIBRARY FREDSBS INITINSTANCE TERMIN STANCE 

3. Rebuild each import library with the IMPLIB utility. For 
example, to rebuild DDE4SBSI.LIB: 

IMPLIB DDE4SBSI.LIB FREDSYS.DEF 

4. Build the startup code into the import library. For example: 

LIB DDE4SBSI.LIB+ DDE4SBSO.LIB 

5. Finally, use the C Set + + DLLRNAME utility to rename the 
actual DLLs. To continue our example with DDE4SBS: 

DLLRNAME DDE4SBS.DLL DDE4SBS= FREDSBS 

As well as the library DLLs, remember to rename the IPMD 
DLLs. The DLLs you need to rename are: 

• DDE4BE32.DLL 

• DDE4BER.DLL 

• DDE4CRT.DLL 

• DDE4CRTP.DLL 

• DDE4MODL.DLL 

• DDE4PMDB.DLL 

• DDE4RESS.DLL 

You'll also need to run the executable for PMD through 
DLLRNAME to ensure that it loads the correct DLLs: 

DLLRNAME IPMD.EXE DDE4BE32= newnamel DDE4BER= newname2 DDE4CRT = 
DDE4CRTP= newname4 DDE4MODL= newname5 DDE4PMDB= newi: 
DDE4RESS= newname7 

where newnamel, newname2, etc are the names you renamed the 
DLLs. 

Of course, if you rename the DLLs from C Set/2, you won't have to 
copy the DLLs from each release to a new directory when setting up 
a release-specific session. 

You're now set to use two versions of C Set at the same time. With 
the announce of C Set + + V2.1, take note that this hint allows you to 
use C Set/2 with either of C Set + + V2.0, or C Set + + V2.1. You 
could conceivably use V2.0 with V2.1, but that's a little more compli¬ 
cated. Maybe next time. 
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Stamps Again 

No, not postage stamps (although we still collect those), but a short 
dissertation on the FWDSTAMP utility: 

This little utility has been part of the OS/2 2.0 toolkit since its initial 
release. It's useful if you are providing an application with a user 
Application Programming Interface (API). Let's assume you are 
providing an application made up of several DLL's, and are pro¬ 
viding APIs to a user, and these API's are scattered among your 
DLLs. 

Providing the APIs to a user via an import library is no problem 
(you use IMPLIB from the toolkit). However, repartitioning your 
APIs between the DLLs is no longer possible, since your DLLs are 
explicitly referenced in the import library. This can create problems 
when you create the next release of your application. 

FWDSTAMP provides a way to provide a fixed user interface, while 
allowing you to repartition your API. What it does is create a "for¬ 
warding stamps" as DLL entry points. These tell the OS/2 loader 
that the entry point is actually located in some other DLL. These 
forwarding stamps have only a small time penalty when your appli¬ 
cation loads, and no time penalty during execution. 

By creating an "interface DLL" made up mainly of forwarding 
stamps, you can now hide the partitioning of your API's code from 
the user of the API. The library you provide to your user refers only 
to the "interface DLL", and references none of your other DLLs. 

The references to your other DLLs is hidden inside the interface 
DLL. By fixing the ordinal numbers of the interface DLL, you can 
provide upward compatibility for your application's API without 
regard to which DLL contains which API. 

Further questions? Write to us using the Reader's Reply From at the 
end of this newsletter, or contact Roger Pett (73251,1733 on Compu¬ 
Serve). 


Roger Wilco 

The fwdstamp article mentioned Roger, one of our developers, the 
one who provided the hint. Many of you may know Ian Ameline as 
our main compiler CompuServe rep, and you're probably wondering 
why we're talking about Roger. Ian has moved to the Browser group 
from the main compiler area, so he's handed over his mantle to 
Roger. Ian will remain on CompuServe where he'll now focus on 
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Browser inquiries. We know Roger will be welcomed by all those 
who haunt our fora. 

For those who don't know, there are over a dozen of us who monitor 
the fora on CompuServe, so if you're looking for help on any compo¬ 
nent of C Set + + , we have you covered. 


Using C Set from the CD-ROM 

Yes, you can use C Set direct from the CD-ROM, thereby saving 
hard disk space. It's not difficult to do, but there are some limita¬ 
tions. In this hint, we've not addressed using WorkFrame/2 in this 
way - it doesn't take a lot of hard disk. Instead we're concentrating 
on the Toolkit and C/C+ + Tools which take up most of the space C 
Set requires. 

Before we tell you how, take note of the following: 

• Corrective Service (CSDs) cannot apply to CD-ROM. 

If you require any fixes or code from a CSD, you have to have 
the component (that the fixes are for) of C Set on your hard 
drive. 

• Running sample programs cannot be done. 

Since sample programs usually generate files, and because 
CD-ROM is a read-only media, running the sample programs in 
CD-ROM-direct mode will fail. 

• Performance may suffer 

Since CD-ROM access time and transfer rate are usually consid¬ 
erably slower than hard drive, running Toolkit and C/C+ + Tools 
in CD-ROM-direct mode will cause performance degradation. 

You might consider leaving some often used EXEs or DLLs on 
your hard drive to balance out performance vs hard disk usage. 


How to make it happen 


If you have Toolkit already installed on your hard drive, but you want 
to use the Toolkit off the CD. 

1. Change drive to your CD-ROM drive. 

2. Change directory to \toolkt21\os2bi. 

3. Type tk21desk. 
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4. When prompted "Is OS/2 Toolkit 2.1 information correct? 

(Y/N)", answer N. 

5. When prompted "Re-enter the Drive that contains Toolkit 2.1", 
type your CD-ROM drive letter, (e.g. L:) 

6. When prompted "Is OS/2 Toolkit 2.1 in drive L:? (Y/N)", answer 
Y. 

7. The tk21desk program will display information on where your 
OS/2 system is and where the Toolkit is. If the information is 
correct, answer Y when prompted "Do you want to continue 
(Y/N)?". 

8. Answer Y when prompted "Do you want to update CON¬ 
FIG.SYS? (Y/N)". 

9. The CONFIG.SYS and desktop folder are now updated to use 
the Toolkit off the CD-ROM. You can now delete the Toolkit 
from your hard drive. 

Note: : if you want to go back to using TK on the hard drive, you 
simply reinstall TK. The reinstallation will update the config.sys and 
the desktop automatically. 

If you have C/C+ + Tools already installed on your hard drive, but you 
want to use the C/C+ + Tools off the CD. 

1. Create a .c file with the following code: 

#define INCL_WINSHELLDATA 
#include < os2.h> 

#include < stdio.h> 

main() { 

BOOL success; 

success = PrfWriteProfileString( HINI_USERPROFILE, 

"IBMCPP201", NULL, NULL ); 

if (success= = FALSE) 

printf("unable to delete IBMCPP201 entry from os2.ini\n"); 
else 

printf("IBMCPP201 successfully removed from os2.ini\n"); 
return; 

} 


2. The .c code will remove the C/C+ + Tools Version 2.01 entry in 
the OS2.INI system file. Compile and run the .c program. You 
should see "IBMCPP201 successfully removed from os2.ini" dis¬ 
played after you ran the program. 


3. Change drive to your CD-ROM drive. 

4. Change directory to \ibmcpp. 

5. Typecppinst. 
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6. Select 'Proceed' when the installation says "cannot find the infor¬ 
mation from the previous C/C+ + Tools installation". Consider 
the installed version of your CD-ROM as your previous installa¬ 
tion of C/C+ + Tools. 

7. Select 'OK' when the installation displays your CD-ROM drive 
and the directory \ibmcpp. 

8. The installed version on the CD-ROM has all options installed. 
When the installation displays the options from the "previous" 
installation, you will see all the options were selected. Select 
'Update' to update your desktop and CONFIG.SYS. 

9. Specify a local directory for DDE4XTRA.SYS and CSE- 
TENV.CMD. A minimal set of files are needed to be installed 
on your hard drive. You can specify any hard drive you want 
including the drive where you previously installed to. Make sure 
you do not erase thse minimal set of files on your hard disk. 

10. Select 'Yes' when prompted "Update CONFIG.SYS?". 

11. The CONFIG.SYS and desktop folder are now updated to use 
the C/C+ + Tools off the CD-ROM. You can now delete the 
C/C+ + Tools from your hard drive except the following: 

• The minimal set of files DDE4XTRA.SYS and CSE- 
TENV.CMD on your hard disk. 

• IBMCPP\WKFRAME directory if you want to keep your 
WorkFrame/2 samples. You cannot run the WorkFrame/2 
samples off the CD because it will create files, and since it is 
a read-only device, it will fail. 

Note: If you want to go back to use C/C+ + Tools on your hard disk, 
you should run the program again (points 1 and 2) and then reinstall 
C/C+ + Tools on your hard drive. 


Back by popular demand 

Although we've published this hint before, new users continue to ask 
about it, so here we are again: 

Using DosCreateThread() vs _beginthread() 

These two functions are similar, but not interchangeable. Either may 
be used by a C Set/2 multithreaded application, noting the following 
differences: 
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D o sCreateT hread() 

_begin thread/) 

Thread function must have linkage 
type _System. 

Thread function must have linkage 
type _Optlink. 

Does not register a C Set/2 
exception handler for the new 
thread. You must do this yourself 
with #pragma handler/) 

Registers a C Set/2 exception 
handler for you on the new thread. 

Thread should never terminate by a 
return. It should always terminate 
with the function _endthread(). 

See the note on DosExitQ, below. 

Thread may terminate by either 
returning, or by calling 
_endthread(). 

Figure 4. Differences 


Using DosExit() vs _endthread() 

These functions are similar, but DosExit() should never be used to 
exit a thread. _endthread() frees storage allocated by the C Set/2 
library for the thread. 


I Was Using the Browser.... 

For those of you who aren't making use of the Browser in C Set + + , 
here are a few basic answers that might get you started. 


Question 

Answer 

Q: Why would I want to use a Browser? 

Program Understanding!!: Suppose you were 
assigned to a project for the first time with thou¬ 
sands of lines of code to support. Or suppose 
you want to use the IBM Class Libraries and 
have no idea where to begin. The Browser is 
the right tool for you. It was created with the 
purpose of helping developers better understand 
source code. 
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Question 

Answer 

Q: Why is the IBM Browser better than other 
ones? 

It provides number of features not found in 
other browsers, including 

• graphical source code view 

• extensive search and query facilities 

• full context-sensitive on-line help and useful 
tutorial 

Q: Why can't the Browser text window find my 
source files? 

This problem is usually seen in one of two sce¬ 
narios: 

• you have installed the C Set+ + product in 
a directory other than C:\IBMCPP and you 
can't see the source for the 
\IBMCPP\SAMPLES\BRO WSERApayroll.brs 
file, or 

• you have moved your source files after gen¬ 
erating the browser (*.BRS) files. 

When the compiler generates browser files, the 
original pathname is contained within the 
browser file itself (e.g., for the sample file it is 
C:\IBMCPP\SAMPLES\BROWSER). So the 
browser will be unable to locate these hardcoded 
pathnames in the text window. If possible, the 
best solution is to recreate your .BRS files from 
the source files; this will place the correct path¬ 
names in the new browser files. 

An alternative is to use the /S option to specify 
the directory where your source files can be 
found for this browser file. For example, 
assume that you have installed C Set+ + onto 
D:\IBMCPP (instead of on C:), you can invoke 
the browser on the command line by: 

CD D:\IBMCPP\SAMPLES\BROWSER 

IBRS.EXE /S. PAYROLL.BRS 

If you are using Workframe/2 then you can 
modify the parameter invocation string for the 
browser, by choosing pull-down Configure, 
option Tools, choosing C+ + Browser, and 
Change, and adding to the end of'Invocation 
string:' the string "/S% d" so it looks like: 

% f /S% d 

If you are drag/dropping browser files on the 

C+ + Browser Icon in the IBM C/C+ + Tools 2 
folder, then you can modify the Parameters 
setting to: 

/S% **P % * 


42 




Question 

Answer 

Q: How do I create browser files? 

(1) The compiler provides a /Fb+ option to 
create browser files. You may also want to use 
the /Fo- option to tell the compiler not to gen¬ 
erate object files, if you are simply interested in 
browsing source code. For example: 

ICC /Fb+ /Fo- payroll.cpp 

Creating implicit rules for .BRS targets in the 
makefiles is also recommended, for example: 
{.J.CPP.BRS: 

ICC.EXE /Fb+ /Fo- A$*.CPP 

(2) Under Workframe/2, choose the "Browser" 
option is checked in the Compiler Options. 

Also see Al, above regarding implicit makefile 
rules. 

Q: How can I load more than one browser file 
at a time? 

(1) The command-line supports wildcard charac¬ 
ters and the load window under the 
Database/Load... option of the control window 
supports multiple selection of browser files. 

(2) Under Workframe/2, you should only load 
one browser file initiall using the Tools menu 
item. Note that you must select a file before 
starting the browser. If you select 2 browser 
files, and invoke the browser via the Tools 

Menu, then 2 copies of the browser are started, 
not one with 2 data files. 

(3) Using the C+ + Browser Icon in the IBM 
C/C+ + Tools 2.0 folder, you should double click 
on the application, then load your browser files 
from the "Load" dialog which is displayed. Do 
not drag/drop more than one browser file onto 
the Icon, since a separate copy of the browser 
will be started for each file so dropped. 
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Question 


Answer 


Use the /X option on the command-line to 
exclude facts from certain directories, such as 
C:\IBMCPP\INCLUDE. For example: 

IBRS.EXE /XC:\IBMCPP\INCLUDE MYFILE.BRS 

If you always want to exclude the same header 
file information, and you are using Workframe/2 
then you can modify the parameter invocation 
string for the browser, by choosing pull-down 
Configure, option Tools, choose C+ + Browser, 
and Change, then adding to the end of'Invoca¬ 
tion string:' the string "/X< path> " so it looks 
like: 

% f /XC:\IBMCPP\INCLUDE 

If you always want to exclude the same header 
file information, and you are drag/dropping 
.BRS files on the C+ + Browser Icon in the IBM 
C/C+ + Tools 2.0 folder, then you can modify the 
Parameters setting to: 

/XC:\IBMCPP\INCLUDE %* 


New York, New York! 

The C Set team attended many shows during the year and continue 
to do so. For you, it's a chance to to take a look at the latest devel¬ 
opments, and just to chat. For us, we can show you our products, 
answer questions, and maybe fix a problem for you. We always 
enjoy meeting you there, and invite you to stop by when you can, 

On February 3rd 1994, one of the developers from the C+ + com¬ 
piler area of the team, will be at the C++ and C SIG meeting in 
New York. He will talk about and demo V2.1 of C Set + + . This 
will be an excellent opportunity to talk to a C+ + developer for the 
evening The venue is expected to be the Conference Centre at IBM 
in New York. 

If you would like more details, or wish to attend, please contact Saul 
Rosenberg about this session at email "rosenbergs@decus.org". 
Internet, AOL, AT&T mail, BIX, CompuServe, Delphi, GEnie and 
MCI addresses are accepted. 


Q: I am not interested in knowing about all the 
C, C+ + , and OS/2 header file stuff. I am mainly 
interested in knowing about my program or 
library. How can I exclude information found in 
the browser files? 
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A Word from your Editor 

In response to the many requests we have received, this newsletter is 
now available softcopy. We're now available on the OS2BBS of 
IBMLink, and in Section 5 of CompuServe. In addition, it has been 
posted, with permission, on several other nets. Please contact us if 
you have any questions about posting electronically. 

If you didn't receive this newsletter mailed direct from IBM, and you 
would like regular hardcopy, then let us know. Mail in the reply 
form at the back with your request to join us, plus your full mailing 
address, and we'll add you to our mailing list, wherever you are. 

Yes, wherever you are...from Argentina to Zaire, if you have a mail 
service, we'll mail you our newsletter. 

For the many of you sending in the reply forms with your comments, 
we've often had the need to call you to discuss your comments 
further. It's a great help if you include your phone number. Thanks! 

This newsletter is available softcopy on several networks. If you 
obtained your copy electronically, you may not be on the C Set + + 
mailing list. If you're not, you're missing out! You're not receiving 
the product information, information updates, and other general 
mailouts that others are. You can be on our list for these goodies, 
with or without hardcopy newsletter distribution. Just mail/fax your 
full address (phone number is handy too) using the Reader's Reply 
Form at the back of this copy, and circle whether you want the NL 
hardcopy, or just want to be added to our mailing list. 
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This newsletter was produced by the OS/2 C/C+ + Planning 
department of the IBM Software Solutions 
Toronto Lab. For further information on any of the 
products mentioned, please contact your local IBM office, or an 
authorized IBM Business Partner. 

Numerous product references in this publication are registered 
trademarks or trademarks of International Business Machines Corporation. 
IBM Canada Ltd., a related company, is a registered user. 

Sample code is provided for information purposes only, and is used 
by readers at their risk. IBM makes an effort to provide accurate and 
safe code examples but does not warrant their correctness. 

This newsletter was created and marked for processing using IBM 
BookMaster (Program Number 5688-015) and IBM Document Composition 
Facility (DCF)™ (Program Number 5748-XX9). 

The final copy was printed on an IBM 3825 Page Printer, an Advancec 
Function Printer. 

This newsletter is e IBM Corporation 1993. 
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IBM C Set + + News No.6 November 93 issue 


Reader's Reply Form 

1. Did you find this newsletter useful? 

2. Is there any way you think we could improve this newsletter? 

3. Is there any compiler-related subject you would like to see addressed in this 
newsletter? 

4. If you received your copy electronically 

• would you prefer to receive hardcopy? 

• would you like to be on our mailing list only (no hardcopy newsletter) 

(circle one) 


Please note: 

• IBM may use or distribute whatever information you supply in any way it 
believes appropriate without incurring any obligation to you, and all such infor¬ 
mation will be considered non-confidential. 

• Do not use this form to report compiler problems or to request copies of publica¬ 
tions. Instead, contact your IBM representative or an authorised IBM Business 
Partner. 

• If you wish, you may include your name, address, and company name if appli¬ 
cable, and your phone number. 


Thank you for your cooperation and help. You can either mail this form to us, or 
hand it into an IBM office for forwarding. 

You can also fax the form to us. Our fax is 416-448-6057. Please mark your fax for 
the attention of MJ Houghton. 







IBM C Set + + News No.6 November 93 issue 
Reader's Reply Form 


Fold here and tape . .fold here and tape . .fold here and tape . .fold here and tape . .fold here and tape . fold 


Software Solutions Toronto Lab 
IBM Canada Ltd 

Workstation Languages Planning D394 

22/394/844/TOR 

844 Don Mills Road 

North York 

Ontario, M3C 1V7 

Canada 


Fold here and tape . .fold here and tape . .fold here and tape . .fold here and tape . .fold here and tape . .fold 


48 




















